Skip to content

docs: Diátaxis site from Org pages - #17

Merged
HaoZeke merged 4 commits into
mainfrom
docs/diataxis
Nov 16, 2026
Merged

HaoZeke merged 4 commits into
mainfrom
docs/diataxis

Conversation

@HaoZeke

@HaoZeke HaoZeke commented Nov 16, 2026

Copy link
Copy Markdown
Collaborator

Docs for eb-keep-logs, built the same way as zig-common's: Org pages rendered by Sphinx, with the API reference generated from the doc comments.

The site has a tutorial, how-tos for running it in a pipeline, rotating a log tree and marking licensed logs, explanations of how the failed build's log is found and how run ages use local time, and a full command reference that covers every message in src/main.zig.

Every pub declaration now has a doc comment. Only comments change in src/, and the release binary has the same sha256 at base and tip.

COMPAT.md gains a section on the differences from the shell script that are bugs: an empty EB_KEEP_LOGS_NOW exits 2, an empty TZDIR and a TZ like :Name that names no file both fall back to UTC, and the runAgeDays comment credits chmod with moving the mtime.

Checks: the strict Sphinx build, check_site.py, the lychee link check, zig fmt --check and zig build test all pass.

The site was the README's text as one Sphinx page, with COMPAT.md and
RELEASING.md beside it. It had no tutorial and no task-sized guides,
and nothing in the code could be linked by name.

The documentation template builds it now. Org pages under
docs/orgmode/ are exported to reStructuredText and built by Sphinx
with warnings and unresolved names as errors. docs/tools/zig_api.zig
writes the API pages from the doc comments of src/main.zig and the
files it imports, and zig build docs installs the Zig autodoc site,
from a compile of its own so that the binary is not built with
-femit-docs. check_site.py checks the internal links and anchors, and
that no page names a site; lychee checks the external links. pixi.lock
pins the tools, so dependabot no longer watches docs/requirements.txt.

The first pages are the tutorial, "Keep a failed build's logs", run
with EasyBuild 5.4.2 as the page says; the how-to on calling
eb-keep-logs from a build pipeline; the explanation of how failed
finds a build's log; and the compatibility table. The contributing
page says how to record a change and run the tests, and links
RELEASING.md. The docs workflow replaces pages.yml: it builds the site
as docbld does, checks the external links, also weekly, and publishes
from main.
The API pages and the autodoc show each declaration's doc comment, and
its first sentence is the summary in the module's list. 11 of the 19
pub declarations had none, nor had five fields of localtime's Posix
and Zone, so their entries were a bare name and a signature. Each now
says what it is or does, with the units, limits and errors the code
has.

The comment at the top of src/localtime.zig said the zone is read the
way glibc reads it. In two cases it is not: an empty TZDIR leaves a
zone name relative to the working directory, where glibc takes it as
unset, and a TZ with a leading ':' that names no file is UTC, where
glibc reads the rule string after the ':'. The comment says so now.
Only comments change: the release binary is the same file, byte for
byte.
COMPAT.md says the Zig build dates runs as date -d does, TZ rules
included, and refuses an EB_KEEP_LOGS_NOW that is not an integer. Run
side by side with the shell script, it differs in three cases that no
row covers:

- EB_KEEP_LOGS_NOW set but empty is refused with exit 2; the shell
  script takes the current time.
- With TZDIR set but empty, a zone name in TZ is looked up relative to
  the working directory, so the zone is UTC; date reads it under
  /usr/share/zoneinfo.
- A TZ with a leading ':' that names no file, such as
  ':CET-1CEST,M3.5.0,M10.5.0/3', is UTC; date reads the rule after
  the ':'.

A new table lists them as unintended differences, and the two rows
that claimed more now say less. The code is unchanged.
The first pages covered one task and one design choice. These are the
rest:

- how-to guides: rotate a log tree, and mark logs that may carry a
  licence number;
- explanation: how a run's age is reckoned from its name in local
  time;
- reference: the eb-keep-logs command, with its arguments, options,
  environment, exit statuses, every message it prints and the files it
  reads and writes, each checked against src/main.zig.

The commands on each how-to page were run as the page says, on the run
the tutorial made, and their output is pasted from that run. The
tutorial, the pipeline how-to and the first explanation link to the
new pages, and an italic lead in that explanation no longer holds a
literal, which reStructuredText cannot nest.
@HaoZeke
HaoZeke merged commit 3933768 into main Nov 16, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant